antsibull-docs

antsibull-docs - TypeScript library for processing Ansible documentation markup

This is a TypeScript library for processing Ansible documentation markup. It is named after the Python package of the same name. It is the TypeScript/JavaScript version of the Python antsibull-docs-parser package, which is used by antsibull-docs.

How to use this

The package is available on npm.

Node.js (CommonJS modules)

const { parse, toHTML } = require('antsibull-docs');

function convert() {
  return toHTML(parse(['First paragraph.', 'Second B(paragraph).']));
}

Webpack (EcmaScript modules)

import { parse, toHTML } from 'antsibull-docs';

function convert(): string {
  return toHTML(parse(['First paragraph.', 'Second B(paragraph).']));
}

How to develop on this

After checking out the repository, run

$ npm install

to install all required node packages. Afterwards you can run

$ npm build

to build the package as both ESM and CJS,

$ npm build:cjs:watch
$ npm build:esm:watch

to start a watch process which builds the package (as CJS or ESM) every time a file is modified,

$ npm test

to run the unit tests,

$ npm run test:coverage

to run the unit tests and output coverage stats,

$ npm run test:watch

to start a watch process which run tests every time a file is modified,

$ npm run test:coverage:watch

to start a watch process which run tests every time a file is modified and outputs coverage stats,

$ npm run lint

to run the linting,

$ npm run format:check

to check formatting with prettier, and

$ npm run format:write

to re-format the source files.

Release

• Update package version in package.json (and remove things like -post0).
• Create changelogs/fragments/<version>.yml with a release_summary section.
• Run rm -rf dist && npm install && npm run build.
• Run npm publish --dry-run and check the output.
• Make sure to run npm run format:write, especially if you updated this README.
• Add modified files to git (if they are OK) and commit with message Prepare <version>..
• Run antsibull-changelog release and add the updated files to git.
• Commit with message Release <version>. and run git tag <version>.
• Run git push upstream main && git push.
• Once CI passes on GitHub, run npm publish.
• On success, do git push upstream --tags and create a GitHub release.
• Add -post0 to the version in package.json, run npm install, commit as Post-release version bump., and push to GitHub.